Welcome to the vTcl Tutorial! We'll guide you through some simple
examples that demonstrate several basic tasks to get you up and
running with vTcl.
Before we can start, we need to make sure we're speaking the same
language and working in the same environment:
o software versions.
o terminology and naming conventions used in this tutorial.
o vTcl user preferences.
Software Versions
=================
If you have older or newer versions of the software, you may find that
some of the descriptions don't match what you see. Hopefully, you'll
still be able to work through the tutorials.
These tutorials are based on the following versions:
tcl 7.6
tk 4.2
vTcl 1.10
Terminology and Naming Conventions for this Tutorial
====================================================
vTcl has several main windows. We'll refer to them by the
abbreviations given in the table below. Some of the vTcl windows are
transient. Your window manager might not decorate them with Title
Bars. The Window menu in the main menu lets you open and close all of
the vTcl main windows.
Abbrev Window Title Bar Short Description
------ ---------------- -----------------
[Attr] Attribute Editor attribute editor for the active widget
[Cons] Visual Tcl Console command console
[Func] Functions list of functions you've defined
[Geom] Attribute Editor geometry parameters for the active widget
[Menu] Visual Tcl main menu: File, Edit, Mode, etc
[Tool] Widget Toolbar palette of widget icons
[Tops] Toplevel Windows list of top level windows you've created
[Tree] Widget Browser widget tree diagram of your application
[Vars] Variables list of global variables you've defined
[Widg] Attribute Editor information for the active widget
Note that [Widg] and [Geom] are actually sections within the [Attr]
window.
Further, we'll refer to a widget within these windows with the
convention "[Abbrev]:widget". This reference means to actually click
the specified widget with the left mouse button. The widget may be a
button, entry field or a sequence of menu items. In the case of the
Widget Toolbar which just contains icons, we give the text of the
balloon help. For example:
[Menu]:File/New - select the "New" item in the "File" menu.
[Tool]:button - select the button widget in the Widget Toolbar.
[Attr]:text - click in the entry field of the "text" item in
the Attribute Editor.
[Attr]:command(...) - click the "..." button for the "command" item in
the Attribute Editor.
Generally, you need to click on an entry field in a vTcl window to
make it active for entry, and you need to press ENTER for the change
to take effect.
There are several auxiliary windows in vTcl for command and function
editing, setting aliases, etc. Here are the windows that we'll be
using:
Abbrev Window Title Bar Short Description
------ -------------------- -----------------
[Alias] Widget Alias for ... entry dialog for widget aliases
[Comm] Command for ... button and menu edit window
[Edit] (toplevel name) function edit window
[Pref] Preferences vTcl preferences
Finally, we'll refer to the windows that _you_ create by names that
we'll assign as they are created. For example:
[Hello] - the window that you create in tutorial #1
[Goodbye] - the window that you create in tutorial #2
A very important window is the Widget Info window, or [Widg], which is
the top section of the Attribute Editor. It shows the following:
o Widget - the name of the selected widget. Except for toplevels,
the active widget is also highlighted with little square
blocks in the corners.
o Class - the type of widget or frame.
o Manager - the geometry manager of the active widget.
o Alias - an alias that you can assign to refer to this widget.
Aliases are stored in an array called "widget".
o Insert - widgets selected from the Widget Toolbar, or [Tool],
will be inserted into this widget or frame.
vTcl user preferences
=====================
vTcl supports several user preference settings in the Preferences
window, [Pref], which you get from [Menu]:File/Preferences. You'll
have to set yours to match what we used here or you'll have
difficulties following the tutorials. If you find your version of vTcl
has more preferences than are defined here, try leaving them in the
default state.
The preferences in these examples were the defaults at the time that
this tutorial was written. Feel free to customize vTcl preferences as
you like after you've finished these tutorials.
The Basics
----------
[X] Use Balloon Help
[ ] Ask for Widget name on insert
[X] Short automatic widget names
[ ] Save verbose widget configuration
[ ] Save global variable values
[ ] Window focus selects window
Default Geometry Manager
------------------------
( ) Grid ( ) Pack (X) Place
Widget Option Encapsulation
---------------------------
(X) List ( ) Braces ( ) Quotes
===========
Tutorial #1
===========
The first time a task is presented, there are extra comments and
instructions. As these basics are repeated, the instructions become
more terse.
1) Start vtcl. Four windows open: [Menu], [Widg], [Func], [Attr].
You'll probably need to move them around so that you can see them
all at once. I like to place the [Attr] window on the right side
of the screen and stretch it to be full height. There's a lot of
info in this one window. Also, depending on the font size that you
use, you may need to stretch the width of this window to see the
little controls on the right edge. For example, [Attr]:command has
a button to the right of the entry field with three dots on it.
2) Check that [Menu]:File/Preferences match the list above.
3) Make sure that you also have the [Tops] window showing.
Turn it on with [Menu]:Window/Toplevels.
Note that [Menu]:Window lets you open and close all of the vTcl
main windows.
4) Create a window.
a - click [Tool]:toplevel
It's the top left square with the blue strip across the top.
Note the balloon help when you hold the mouse still over an icon
for a couple of seconds! Have a look at the balloon help for each
icon now to get familiar with what they are.
Note also that [Widg], [Attr] and [Geom], which are actually all
in the Attribute Editor window, filled up with info and options
for the toplevel window just created. The information in these
windows changes as you select different widgets by clicking on
them with the left mouse button to make them active.
5) Change the title of the window.
a - click [Geom]:title
b - erase the default title: New Toplevel 1
c - type our new title: Hello
d - press ENTER.
Note that the title bar of your new window changes, as does the
name in the [Tops] window.
6) Create a button in the window.
a - click [Tool]:button
Note the button created in the Hello window!
7) Change the text on the button.
a - click [Attr]:Text
b - erase: button
c - type: Say Hello
d - press ENTER
Note that the text of the button changes to "Say Hello".
8) Give the button something to do when it's clicked.
a - click [Attr]:Command(...)
Note the [Comm] editor window that pops up
b - type in the [Comm] editor window: puts "Hello, World!"
c - click [Comm]:OK
9) Move the button around to make it look nice.
The "Place" geometry manager allows you to simply drag and drop
widgets in the window to reposition them. Don't drag the little
black squares in the corners: they resize the button itself.
Click and drag the center of the button.
In your [Hello] window,
a - Try moving your "Say Hello" button to the middle of the
window. Also try resizing the whole window itself using the
normal window manager methods (dragging window corners and
edges) to make it all look nice.
10) Save your program to a disk file.
a - click [Menu]:File/SaveAs
b - type the name hello1.tcl in the Selection field.
c - click Save or press Enter.
It's now ready to run by executing "wish hello1.tcl", or
"chmod 755 hello1.tcl" and execute it directly as "hello1.tcl".
On UNIX systems, the message is written to the xterm where you execute
the program. If you're on some other platform and you don't see the
message anywhere, just go on to the next tutorial where we add a
pop-up window for the message.
===========
Tutorial #2
===========
Tutorial #1 can be improved by popping up a hello window rather than
just writing to stdout.
If you are continuing from the same vTcl session as Tutorial #1,
you're ready to go. Otherwise, [Menu]:File/Close any existing
application then [Menu]:File/Open the file "hello1.tcl" from Tutorial
#1.
Besides creating and hiding a second window, this tutorial introduces
the very useful "alias" feature. You name widgets and toplevels and
then refer to them by name using the "widget" array. This avoids
having to use the long complicated names that are generated.
1) Make sure that you have these windows showing:
[Menu], [Widg], [Func], [Attr], [Tops].
Turn on any missing windows with [Menu]:Window.
2) Create a second toplevel window.
a - click [Tool]:toplevel
3) Change the title of the window.
a - click [Geom]:title
b - erase the default title: New Toplevel 2
c - type our new title: Goodbye
d - press ENTER
4) Give the button an alias for easy reference.
a - click [Menu]:Options/SetAlias
Note the little alias entry window pops up.
b - type: msg
c - click [Alias]:OK
5) Put a message in the window.
a - click [Tool]:message
Note that a message widget is added to the active window.
6) Change the message text to the familiar friendly greeting.
a - click [Attr]:Text
b - erase: message
c - type: Hello, World!
d - press ENTER
7) Change the aspect ratio attribute to put the message all on one
line.
a - click [Attr]:Aspect
a - change 150 to some bigger number (1500 will do)
b - press ENTER
Note how the message all fits on one line now.
8) Now add a button to the window.
a - click [Tool]:button
Note that the button is placed on top of the message, but we'll
move it in a minute.
9) Change the text on the button.
a - click [Attr]:Text
b - erase: button
c - type: Goodbye
d - press ENTER
10) Move the button and message around to make it all look nice.
In the [Goodbye] window,
a - Drag the "Goodbye" button down so it's not covering the
"Hello" message.
b - Arrange the placement of the two widgets and resize the window
itself using the normal window manager controls to make it all
look nice.
11) Make sure the Goodbye button is the active widget.
a - click [Goodbye]:Goodbye
By clicking the "Goodbye" button, you "select" it for editing.
Note the little black squares in the corners to indicate this. If
you just finished dragging the "Hello" message, the "Goodbye"
button wouldn't be the active (selected) widget.
12) Give the Goodbye button a command to hide the [Goodbye] window.
a - click [Attr]:Command(...)
b - type in the [Comm] window: Window hide $widget(msg)
c - click [Comm]:OK
13) Position the goodbye window.
Drag the [Goodbye] window (by the window manager title bar) to
place it where you want it to pop up when you execute the program.
vTcl enters this geometry placement into your application, but not
all window managers will honor this placement.
14) Hide the [Goodbye] window.
In the [Tops] window,
a - select Goodbye in the listbox
b - click [Tops]:Hide
When you click [Menu]:File/Save to save your applications, make
sure that you have your toplevel windows showing or hidden as you
would want them to be when a user runs your application. In our
program, if you save it with the "Goodbye" window showing, the
user will get both windows at startup.
15) Give the "Hello" button the command to show the second window.
In the [Hello] window,
a - click the "Hello" button to make it active.
b - click [Attr]:Command(...)
c - erase: puts "Hello, World!"
d - type: Window show $widget(msg)
e - click [Comm]:OK
16) Save your program to a disk file.
a - click [Menu]:File/SaveAs
b - type the name hello2.tcl in the Selection field.
c - click Save or press Enter.
It's now ready to run by executing "wish hello2.tcl", or
"chmod 755 hello2.tcl" and execute it directly as "hello2.tcl".
Click "Say Hello", and the Goodbye window pops up. Click "Goodbye"
and the window goes away again.
===========
Tutorial #3
===========
If you are continuing from the same vTcl session as Tutorial #2,
you're ready to go. Otherwise, [Menu]:File/Close any existing
application then [Menu]:File/Open the file "hello2.tcl" from Tutorial
#2.
In [Menu]:Mode are items that toggle between EDIT and TEST mode. We've
been in EDIT mode up to this point. TEST mode allows you to actually
run your application from within vTcl! The current mode is shown on
the bottom line of the [Menu] window. This indicator is in fact a
convenience button that you can click to toggle between the two modes.
1) Change to TEST mode to test the program from within vTcl.
a - click [Menu]:Mode/TestMode
Note that the indicator in the [Menu] window changes to show TEST.
Now you can click the "Hello" and "Goodbye" buttons and see that
the application works without leaving vTcl!
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Last modified: 12 May 1997
Written by Rick Macdonald , with suggestions from:
Stewart Allen
Larry W. Virden
Your feedback is welcome!